home *** CD-ROM | disk | FTP | other *** search
- =head1 NAME
-
- Glib::BookmarkFile - Parser for bookmark files
-
- =cut
-
- =for position SYNOPSIS
-
- =head1 SYNOPSIS
-
- use Glib;
-
- $date .= $_ while (<DATA>);
-
- $b = Glib::BookmarkFile->new;
- $b->load_from_data($data);
- $uri = 'file:///some/path/to/a/file.txt';
- if ($b->has_item($uri)) {
- $title = $b->get_title($uri);
- $desc = $b->get_description($uri);
-
- print "Bookmark for `$uri' ($title):\n";
- print " $desc\n";
- }
- 0;
-
- __DATA__
- <?xml version="1.0" encoding="UTF-8"?>
- <xbel version="1.0"
- xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks"
- xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info">
- <bookmark href="file:///tmp/test-file.txt" added="2006-03-22T18:54:00Z" modified="2006-03-22T18:54:00Z" visited="2006-03-22T18:54:00Z">
- <title>Test File</title>
- <desc>Some test file</desc>
- <info>
- <metadata owner="http://freedesktop.org">
- <mime:mime-type type="text/plain"/>
- <bookmark:applications>
- <bookmark:application name="Gedit" exec="gedit %u" timestamp="1143053640" count="1"/>
- </bookmark:applications>
- </metadata>
- </info>
- </bookmark>
- </xbel>
-
- =for position DESCRIPTION
-
- =head1 DESCRIPTION
-
- B<Glib::BookmarkFile> lets you parse, edit or create files containing lists
- of bookmarks to resources pointed to by URIs, with some meta-data bound to
- them, following the Desktop Bookmark Specification. The recent files support
- inside GTK+ uses this type of files to store the list of recently used
- files.
-
- The syntax of bookmark files is described in detail in the Desktop Bookmarks
- Specification, here is a quick summary: bookmark files use a subclass of the
- XML Bookmark Exchange Language (XBEL) document format, defining meta-data
- such as the MIME type of the resource pointed by a bookmark, the list of
- applications that have registered the same URI and the visibility of the
- bookmark.
-
- =cut
-
-
-
- =for object Glib::BookmarkFile Parser for bookmark files
- =cut
-
-
-
-
- =head1 METHODS
-
- =head2 bookmarkfile = Glib::BookmarkFile-E<gt>B<new>
-
- =head2 $bookmark_file-E<gt>B<add_application> ($uri, $name, $exec)
-
- =over
-
- =item * $uri (string)
-
- =item * $name (string or undef)
-
- =item * $exec (string or undef)
-
- =back
-
- Adds the application with $name and $exec to the list of
- applications that have registered a bookmark for $uri into
- $bookmark_file.
-
- Every bookmark inside a C<Glib::BookmarkFile> must have at least an
- application registered. Each application must provide a name, a
- command line useful for launching the bookmark, the number of times
- the bookmark has been registered by the application and the last
- time the application registered this bookmark.
-
- If $name is undef, the name of the application will be the
- same returned by Glib::get_application_name(); if $exec is undef,
- the command line will be a composition of the program name as
- returned by Glib::get_prgname() and the "%u" modifier, which will
- be expanded to the bookmark's URI.
-
- This function will automatically take care of updating the
- registrations count and timestamping in case an application
- with the same $name had already registered a bookmark for
- $uri inside the bookmark file. If no bookmark for $uri is found
- one is created.
-
- =head2 $bookmark_file-E<gt>B<add_group> ($uri, $group)
-
- =over
-
- =item * $uri (string)
-
- =item * $group (string)
-
- =back
-
- Adds $group to the list of groups to which the bookmark for $uri
- belongs to. If no bookmark for $uri is found one is created.
-
- =head2 unix timestamp = $bookmark_file-E<gt>B<get_added> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- =for apidoc __gerror__
- Gets the time the bookmark for $uri was added to $bookmark_file.
-
- =head2 $bookmark_file-E<gt>B<set_added> ($uri, $value)
-
- =over
-
- =item * $uri (string)
-
- =item * $value (unix timestamp)
-
- =back
-
- Sets the time the bookmark for $uri was added.
- If no bookmark for $uri is found one is created.
-
- =head2 ($exec, $count, $stamp) = $bookmark_file->B<get_app_info> ($uri, $name)
-
- =over
-
- =item * $uri (string)
-
- =item * $name (string)
-
- =back
-
- Gets the registration informations of $name for the bookmark for
- $uri. See Glib::BookmarkFile::set_app_info() for more informations about
- the returned data.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_app_info> ($uri, $name, $exec, $count, $stamp)
-
- =over
-
- =item * $uri (string)
-
- =item * $name (string)
-
- =item * $exec (string)
-
- =item * $count (integer)
-
- =item * $stamp (unix timestamp)
-
- =back
-
- Sets the meta-data of application $name inside the list of
- applications that have registered a bookmark for $uri inside
- $bookmark_file.
-
- You should rarely use this method; use Glib::BookmarkFile::add_application()
- and Glib::BookmarkFile::remove_application() instead.
-
- $name can be any UTF-8 encoded string used to identify an application.
- $exec can have one of these two modifiers: "%f", which will be expanded
- as the local file name retrieved from the bookmark's URI; "%u", which
- will be expanded as the bookmark's URI. The expansion is done automatically
- when retrieving the stored command line using the
- Glib::BookmarkFile::get_app_info() method.
- $count is the number of times the application has registered the
- bookmark; if it is < 0, the current registration count will be increased
- by one, if it is 0, the application with $name will be removed from
- the list of registered applications.
- $stamp is the Unix time of the last registration, as returned by time(); if
- it is -1, the current time will be used.
-
- If you try to remove an application by setting its registration count to
- zero, and no bookmark for $uri is found, %FALSE is returned and an
- exception is fired.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 list = $bookmark_file->B<get_applications> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Retrieves the names of the applications that have registered the
- bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file->B<get_description> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Gets the description of the bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_description> ($uri, $description)
-
- =over
-
- =item * $uri (string)
-
- =item * $description (string)
-
- =back
-
- Sets the description of the bookmark for $uri. If no bookmark for $uri
- is found one is created.
-
- =head2 list = $bookmark_file-E<gt>B<get_groups> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Retrieves the list of group names of the bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_groups> ($uri, ...)
-
- =over
-
- =item * $uri (string)
-
- =item * ... (list) one or more group names
-
- =back
-
- Sets a list of group names for the item with URI $uri. Each previously
- set group name list is removed. If no bookmark for $uri is found one
- is created.
-
- =head2 boolean = $bookmark_file-E<gt>B<has_application> ($uri, $name)
-
- =over
-
- =item * $uri (string)
-
- =item * $name (string)
-
- =back
-
- Checks whether the bookmark for $uri inside $bookmark_file has
- been registered by application $name.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 boolean = $bookmark_file-E<gt>B<has_group> ($uri, $group)
-
- =over
-
- =item * $uri (string)
-
- =item * $group (string)
-
- =back
-
- Checks whether $group appears in the list of groups to which
- the bookmark for $uri belongs to.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 boolean = $bookmark_file-E<gt>B<has_item> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Looks whether the bookmark file has a bookmark for $uri.
-
- =head2 ($href, $mime_type) = $bookmark_file->B<get_icon> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Gets the icon of the bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_icon> ($uri, $href, $mime_type)
-
- =over
-
- =item * $uri (string)
-
- =item * $href (string or undef)
-
- =item * $mime_type (string or undef)
-
- =back
-
- Sets the icon for the bookmark for $uri. If $href is undef, unsets
- the currently set icon.
-
- =head2 boolean = $bookmark_file-E<gt>B<get_is_private> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
-
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_is_private> ($uri, $is_private)
-
- =over
-
- =item * $uri (string)
-
- =item * $is_private (boolean)
-
- =back
-
-
-
- =head2 $bookmark_file-E<gt>B<load_from_data> ($buf)
-
- =over
-
- =item * $buf (scalar)
-
- =back
-
- Parses a string containing a bookmark file structure.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 ($full_path) = $bookmark_file->B<load_from_data_dirs> ($file)
-
- =over
-
- =item * $file (localized file name)
-
- =back
-
-
- Parses a bookmark file, searching for it inside the data directories.
- If a file is found, it returns the full path.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<load_from_file> ($file)
-
- =over
-
- =item * $file (localized file name)
-
- =back
-
- Parses a bookmark file.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 string = $bookmark_file-E<gt>B<get_mime_type> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Gets the MIME type of the bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_mime_type> ($uri, $mime_type)
-
- =over
-
- =item * $uri (string)
-
- =item * $mime_type (string)
-
- =back
-
- Sets the MIME type of the bookmark for $uri. If no bookmark for $uri
- is found one is created.
-
- =head2 unix timestamp = $bookmark_file-E<gt>B<get_modified> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- =for apidoc __gerror__
- Gets the time the bookmark for $uri was last modified.
-
- =head2 $bookmark_file-E<gt>B<set_modified> ($uri, $value)
-
- =over
-
- =item * $uri (string)
-
- =item * $value (unix timestamp)
-
- =back
-
- Sets the time the bookmark for $uri was last modified.
- If no bookmark for $uri is found one is created.
-
- =head2 $bookmark_file-E<gt>B<move_item> ($old_uri, $new_uri)
-
- =over
-
- =item * $old_uri (string)
-
- =item * $new_uri (string or undef)
-
- =back
-
- Changes the URI of a bookmark item from $old_uri to $new_uri. Any
- existing bookmark for $new_uri will be overwritten. If $new_uri is
- undef, then the bookmark is removed.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<remove_application> ($uri, $name)
-
- =over
-
- =item * $uri (string)
-
- =item * $name (string)
-
- =back
-
- Removes application registered with $name from the list of applications
- that have registered a bookmark for $uri inside $bookmark_file.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<remove_group> ($uri, $group)
-
- =over
-
- =item * $uri (string)
-
- =item * $group (string)
-
- =back
-
- Removes $group from the list of groups to which the bookmark
- for $uri belongs to.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<remove_item> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Removes the bookmark for $uri from the bookmark file.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 integer = $bookmark_file-E<gt>B<get_size>
-
- Gets the number of bookmarks inside the bookmark file.
-
- =head2 $bookmark_file->B<get_title> ($uri, $title)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- Gets the title of the bookmark for $uri.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<set_title> ($uri, $title)
-
- =over
-
- =item * $uri (string)
-
- =item * $title (string)
-
- =back
-
- Sets the title of the bookmark for $uri. If no bookmark for $uri is found
- one is created.
-
- =head2 string = $bookmark_file-E<gt>B<to_data>
-
- Returns the bookmark file as a string.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 $bookmark_file-E<gt>B<to_file> ($file)
-
- =over
-
- =item * $file (localized file name)
-
- =back
-
- Saves the contents of a bookmark file into a file. The write operation
- is guaranteed to be atomical by writing the contents of the bookmark file
- to a temporary file and then moving the file to the target file.
-
- May croak with a L<Glib::Error> in $@ on failure.
-
- =head2 list = $bookmark_file->B<get_uris>
-
- Returns the URI of all the bookmarks in the bookmark file.
-
- =head2 unix timestamp = $bookmark_file-E<gt>B<get_visited> ($uri)
-
- =over
-
- =item * $uri (string)
-
- =back
-
- =for apidoc __gerror__
- Gets the time the bookmark for $uri was last visited.
-
- =head2 $bookmark_file-E<gt>B<set_visited> ($uri, $value)
-
- =over
-
- =item * $uri (string)
-
- =item * $value (unix timestamp)
-
- =back
-
- Sets the time the bookmark for $uri was last visited.
- If no bookmark for $uri is found one is created.
-
-
-
- =cut
-
-
- =head1 SEE ALSO
-
- L<Glib>
-
-
- =cut
-
-
- =head1 COPYRIGHT
-
- Copyright (C) 2003-2009 by the gtk2-perl team.
-
- This software is licensed under the LGPL. See L<Glib> for a full notice.
-
-
-
- =cut
-
-